Reading Workout Samples#

The Scripting app allows you to retrieve workout sessions from HealthKit using the global Health.queryWorkouts() function. Workouts represent physical activity sessions such as running, walking, swimming, cycling, strength training, and more.

Each workout includes metadata such as duration, activity type, start/end times, and detailed statistics like heart rate, distance, and energy burned.

What Is a Workout?#

A HealthWorkout record contains:

• startDate / endDate: The duration of the workout session
• duration: Total duration in seconds
• workoutActivityType: Enum representing the workout type (e.g., running, walking)
• metadata: Optional custom metadata
• workoutEvents: Optional array of workout-related events (e.g., pauses, laps)
• allStatistics: A dictionary of detailed quantity statistics (e.g., heart rate, distance, calories)

API Overview#

1Health.queryWorkouts(
2  options?: {
3    startDate?: Date
4    endDate?: Date
5    limit?: number
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    sortDescriptors?: Array<{
9      key: "startDate" | "endDate" | "duration"
10      order?: "forward" | "reverse"
11    }>
12    requestPermissions?: HealthQuantityType[]
13  }
14): Promise<HealthWorkout[]>

Parameters#

Example: Read Recent Workouts#

1const workouts = await Health.queryWorkouts({
2  startDate: new Date("2025-07-01"),
3  endDate: new Date("2025-07-05"),
4  sortDescriptors: [{ key: "startDate", order: "reverse" }]
5})
6
7for (const workout of workouts) {
8  console.log("Workout Type:", workout.workoutActivityType)
9  console.log("Start:", workout.startDate)
10  console.log("End:", workout.endDate)
11  console.log("Duration (min):", workout.duration / 60)
12
13  const heartRate = workout.allStatistics["heartRate"]
14  const energy = workout.allStatistics["activeEnergyBurned"]
15
16  if (heartRate) {
17    const avgHR = heartRate.averageQuantity(HealthUnit.count().divided(HealthUnit.minute()))
18    console.log("Avg Heart Rate:", avgHR)
19  }
20
21  if (energy) {
22    const kcal = energy.sumQuantity(HealthUnit.kilocalorie())
23    console.log("Calories Burned:", kcal)
24  }
25
26  console.log("---")
27}

Accessing Detailed Statistics#

The allStatistics dictionary provides detailed quantity data recorded during the workout. You can extract values using:

1const stat = workout.allStatistics["heartRate"]
2const avg = stat?.averageQuantity(HealthUnit.count().divided(HealthUnit.minute()))
3const max = stat?.maximumQuantity(HealthUnit.count().divided(HealthUnit.minute()))

Common available statistics include:

• "heartRate"
• "activeEnergyBurned"
• "distanceWalkingRunning"
• "stepCount"

Workout Events (Optional)#

If recorded, workout.workoutEvents contains an array of time-stamped workout events:

1for (const event of workout.workoutEvents || []) {
2  console.log("Event:", event.type)
3  console.log("From:", event.dateInterval.start)
4  console.log("To:", event.dateInterval.end)
5}

Event types include: pause, resume, lap, segment, motion pause/resume, etc.

Notes#

• Each workout is an instance of HealthWorkout
• workoutActivityType is an enum, which you can map to labels or icons
• If allStatistics is missing some keys, the data may not have been recorded by the device/app
• You can combine workout data with category and quantity samples for full activity insights

Summary#

To read workouts from HealthKit:

1. Call Health.queryWorkouts(options) to get a list of HealthWorkout records
2. Use startDate, endDate, and sorting options to filter and order results
3. Access properties like duration, activityType, and allStatistics for insights
4. Optionally inspect workoutEvents and metadata

This API is ideal for analyzing exercise history, generating workout summaries, or visualizing fitness trends.